=========================================================================
ISTRUZIONI e SPECIFICHE per il PRIMO FRAMMENTO del PROGETTO di LCS 08/09
========================================================================

Il progetto ZTL e' suddiviso in  tre frammenti.
Il primo e' descritto in questo README.

Il primo frammento del progetto prevede l'implementazione di una
libreria che manipola i permessi di accesso alla ZTL e li organizza
utilizzando un albero di ricerca ordinato (libztl.a). 

Questo primo frammento e' realizzabile usando esclusivamente C sequenziale (vedi
programma LLS).


------------------------------------------------
Estrarre il materiale dal KIT di progetto
------------------------------------------------
Creare una directory temporanea, copiare lcsZTL_kitf1.tar  
nella directory e spostarsi nella directory appena creata. Es.

$$ mkdir Frammento1
$$ mv lcsZTL_kitf1.tar Frammento1
$$ cd Frammento1

S-tarare i file del primo kit con

$$ tar xvf lcsZTL_kitf1.tar 

questa operazione crea nella directory corrente una directory "ZTL" che
contiene le seguenti sottodirectory:

$$ ls ZTL
Doc/  lib/  Src/ Test/

Doc/ contiene la documentazione formato doxygen
lib/ contiene le librerie
Src/ contiene sorgenti, header, Makefile
Test/ contiene altre due sottodirectory con i
      unitari per il codice della libreria

========================================================================
ISTRUZIONI per la realizzazione della libreria libztl.a
========================================================================

Il progetto prevede la realizzazione di una libreria di funzioni (libztl.a)
utilizzata dal server per manipolare i permessi ZTL.

Le funzioni da realizzare sono specificate nei file

Src/intervals.h 
Src/ilist.h
Src/ptree.h

Tali file contengono i prototipi delle funzioni da
realizzare, i tipi di dato e le define relative.

E' possibile generare la documentazione doxygen per questi file invocando

  bash:~$ make docu

nella directory Src/ dopo l'esecuzione visualizzare 

../Doc/html/index.html

con un qualsiasi browser.

Il kit fornisce tre diversi test per verificare il funzionamento della
libreria. 

1) TEST-1 Un primo test e' contenuto nel file

Src/test-libztl.c

2) TEST-2 un test unitario sulle varie funzioni di intervals.h e ilist.h  e'
contenuto nellla directory 

../Test/Test1

3) TEST-3 un test unitario sulle varie funzioni di ptree.h  e'
contenuto nellla directory 

../Test/Test2


TEST-2 e TEST-3 utilizzano la libreria cunit. Prima di utilizzare
questi due programmi ditest leggere ATTENTAMENTE il file
Test/README.testing ed a provare ad eseguire il file Test/cunit.c
I test TEST-2 e TEST-3 assumono che la libreria sia stata compilata e copiata nella directory

lib/

I test possono essere invocati o com "make test" nelle rispettive directory
o con "make test1" e "make test2" nella directory Src (questa dir) 

------------------------------------------------------------------
File contenuti in Src
------------------------------------------------------------------

$$ ls Src/

gruppo-check.pl   README-1
gruppo.txt        intervals.h 
ilist.h		  test-libztl.c	  
Makefile	  ptree.h
README.doxygen

-----------------------------------------------
Descrizione del contenuto dei file 
-----------------------------------------------

README-1		: questo file


gruppo-check.pl		: uno script Perl che controlla il formato del file
			  gruppo.txt prima di effettuare la consegna
			  (NON MODIFICARE)

gruppo.txt		: un file di esempio di specifica del gruppo
			  (solo 1 studente per gruppo)
			  (deve essere aggiornato con i dati di chi consegna,
			  secondo il formato esemplificato)

test-libztl.c		: un programma di test per il test iniziale del codice
                          prodotto (NON MODIFICARE)

intervals.h ilist.h ptree.h
			: tipi e prototipi delle funzioni da realizzare
			  nel primo frammento
			  (si possono modificare solo aggiungendo
			  campi/definizioni/prototipi senza MODIFICARE/ELIMINARE
			  quelli gia' esistenti)

Makefile		: makefile per il test del frammento e la
			  consegna 
			  (MODIFICARE SOLO nelle parti richieste, vedi
			  commenti nel file)

README.doxygen		:  breve descrizione di doxygen, 
                             con rimandi ai siti rilevanti
			     per chi desidera usarlo per la
                             documentazione del codice (facoltativo)


------------------------------------------------
Cosa deve essere realizzato per il primo frammento :
------------------------------------------------

Il primo frammento prevede la realizzazione di una libreria con cui
manipolare i permessi ZTL.

Le strutture dati da utilizzare per rappresentare tali permessi e
memorizzarli sono definite nei file .h insieme al formato con cui vengono serializzati su file:

 XXXXXXX gg/mm/aaaa-hh:mm gg/mm/aaaa-hh:mm 

(targa (XXXXXX) in lettere/numeri 
inizio--fine giorno/mese/anno-ore:minuti) 
notare che le tre stringhe sono separate da un singolo spazio.

Negli stessi file sono definiti e commentati i 
prototipi delle funzioni da realizzare.

I commenti in *.h spiegano le strutture dati da utilizzare
il comportamento delle varie funzioni, il significato dei parametri ed
i valori ritornati. La sintassi utilizzata e' quella di doxygen, un tool per
la creazione della documentazione 'tipo javadoc' comunemente utilizzato.
Chi vuole utilizzarlo per la produzione della documentazione puo' leggere
il README.doxygen.

Per generare la documentazione html dei file contenuti nel kit basta invocare

  bash:~$ make docu

e poi visualizzare il file ../Doc/html/index.html con un browser.

Le funzioni definite in intervals.h vengono naturalmente utilizzate
nella realizzazione delle altre funzioni, mentre le funzioni definite
in ilist.h vengono utilizzate in ptree.h. 
E' quindi ragionevole procedere nel seguente modo:. Prima realizzare
le funzioni in intervals.h in un corrispondente "intervals.c" e testarle.
Quando siamo ragionevolmente convinti della correttezza passare
alla realizzazione delle funzioni in ilist.h e testarle. Infine
realizzare le funzioni in ptree.h e testarle.

Le funzioni definite in un dato file XXX.h possono essere realizzate
usando un singolo file (in questo caso PER CONVENZIONE il file viene
chiamato XXX.c) o in piu' file (di cui uno e' comunque XXX.c).
In ogni caso il Makefile deve essere esteso con i target
corrispondenti a

intervals.o
ilist.o
ptree.o

e dalle corrette liste di dipendenze.

Inoltre, il Makefile contiene una variabile 
FILE_DA_CONSEGNARE
che deve contenere tutti i file prodotti.

------------------
Come procedere :
-----------------

0) leggere attentamente il README e capire il funzionamento il codice fornito
   dai docenti 

1) analizzare accuratamente il file test-libztl.c per capire il tipo di test
   effettuati 

2) implementare le funzioni richieste in uno o piu' file
   ed effettuare testing preliminare utilizzando un main() sviluppato 
   allo scopo

3) testare il software complessivo con il main() (test-libztl.c) fornito dai
  docenti (usando il Makefile " make testiniziale"). E' necessario
  prima settare la variabile di 
  ambiente MALLOC_TRACE in modo che contenga "./.mtrace" e poi
  procedere al test invocando il target "test", cioe' eseguire:

       bash:~$ export MALLOC_TRACE="./.mtrace"
       bash:~$ make testiniziale

  NOTA: (1) tutti i file sviluppati per la soluzione si devono trovare nella
  directory Src/
  (2) E' importante che il test venga effettuato solo su
  un programma gia' funzionante altrimenti i risultati possono essere di
  difficile interpretazione, fuorvianti o inutili.

4) Quando la libreria e' stabile effettuare i test unitari nelle
   directory Test/Test1 e Test/Test2 
   Anche in questo caso la variabile  MALLOC_TRACE deve contenere
   "./.mtrace"

   NOTA: (1) prima di effetuare questi test assicurarsi che l'ultima
   versione della libreria si trovi nella directory lib/ l'invocazione
   	    bash:~$ make lib
   ricrea la libreria e la copia in tale directory
   (2) l'invocazione dei test unitari puo' essere invocata con "make
   test" nelle rispettive directory

5) preparare la documentazione: ovvero commentare adeguatamente il/i file che
   contengono la soluzione  ed inserire una intestazione contenente il nome
   dello sviluppatore ed una dichiarazione di originalita' 

   /** \file pippo.c
       \author Nino Bixio
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale dell' autore.  */

     Non e' richiesto di preparare anche la documentazione formato
     doxygen. Chi volesse farlo e' invitato a leggere il  README.doxigen.

5) aggiornare il file "gruppo.txt" con nome e dati

6) consegnare il file ESCLUSIVAMENTE eseguendo

      bash:~$ make consegna

   e seguendo le istruzioni. Anche in questo caso occorre  che la variabile
   MALLOC_TRACE sia settata  a "./.mtrace".
   Per la consegna e' necessaria l'utility "mpack" installata solo nelle
   macchine dei laboratori H, M ed I. Per consegne da altre macchine e'
   possibile scaricare il binario di 'mpack' dal sito del corso oppure
   semplicemente allegare il tar file creato dal make consegna ad un
   normale messaggio di mail con subject "lcs09: consegna primo
   frammento".

   Tutte le consegne verranno confermate con un messaggio entro 2/3
   giorni. In caso questo non si verifichi contattare il docente.
   

---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) gli eleborati non consegnati con "make consegna" o con un tar non
creato da "make consegna" non verranno accettati

2) tutti gli elaborati verranno confrontati fra di loro con tool automatici
   per stabilire eventali situazioni di PLAGIO. Se tali situazioni si
   verificheranno *tutti* gli elaborato coinvolti verranno annullati con
   conseguente perdita del bonus. 

3) Tutti gli studenti coinvolti in un episodio di PLAGIO comprovato dovranno
   re-implementare il frammento incriminato e saranno sottoposti ad una prova
   orale supplementare. In caso di recidive verranno esclusi dalla
   possibilita' di sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO
   IN CORSO.

4) Chi in sede di orale risulta palesemente non essere l'autore del software
   consegnato in uno dei frammenti verra' escluso dalla possibilita' di
   sostenere l'esame per TUTTO IL RESTO DELL'ANNO ACCADEMICO IN CORSO.

5) Tutti i comportamenti scorretti ai punti 3 e 4 verranno segnalati
   ufficialmente al presidente del corso di laurea, che si riserva di
   decidere azioni disciplinari supplementari a quelle sopra descritte.

----------------------------
 VALUTAZIONE DEL FRAMMENTO:
----------------------------

Gli studenti che consegnano una versione funzionante e ragionevolmente
corretta del frammento entro la data di scadenza accumulano un bonus di 2
punti che verra' sommato al voto finale (vedi lucidi lezioni ed
esercitazioni).

La qualita' del codice consegnato per il primo frammento verra' valutata come
parte del progetto finale e contribuira' alla votazione assegnata al progetto.
Eventuali caratteristiche in piu' rispetto a quelle strettamente richieste
dalle specifiche date qua (es. documentazione HTML o in altri
formati, bilanciamento alberi in ptree) verranno valutate in questa sede.
